Skip to main content

Webhook Controller Guide

The webhook controller receives awareness protocol packets from the eVault system and saves them to your local database.

What the Webhook Receives​

The webhook endpoint (POST /api/webhook) receives awareness protocol packets with the following structure:

{
  "id": "global-id-123",
  "schemaId": "schema-w3id",
  "w3id": "https://evault.example.com/users/123",
  "data": {
    "displayName": "John Doe",
    "username": "johndoe",
    // ... other fields according to the global schema
  }
}

The schemaId (see Ontology) identifies which mapping to use for transforming the data, and data contains the entity information in the global ontology format.

What to Do​

  1. Find the mapping using the schemaId:
const mapping = Object.values(this.adapter.mapping).find(
    (m: any) => m.schemaId === schemaId
);
  1. Convert from global to local using the Web3 Adapter's fromGlobal method:
const local = await this.adapter.fromGlobal({
    data: req.body.data,
    mapping,
});

This method uses your mapping configuration to transform the global ontology data into your local database schema format. See the Mapping Rules for details on creating mappings.

  1. Check if entity exists using the global ID:
let localId = await this.adapter.mappingDb.getLocalId(req.body.id);
  1. Save or update the entity in your database:
    • If localId exists, update the existing entity
    • If not, create a new entity and store the mapping:
await this.adapter.mappingDb.storeMapping({
    localId: entity.id,
    globalId: req.body.id,
});
  1. Return success:
res.status(200).send();

Implementation Example​

Here's a simplified example from @eCurrency-api:

handleWebhook = async (req: Request, res: Response) => {
    const globalId = req.body.id;
    const schemaId = req.body.schemaId;
    
    try {
        // Find mapping
        const mapping = Object.values(this.adapter.mapping).find(
            (m: any) => m.schemaId === schemaId
        );
        
        if (!mapping) {
            throw new Error("No mapping found");
        }

        // Convert global to local
        const local = await this.adapter.fromGlobal({
            data: req.body.data,
            mapping,
        });

        // Check if exists
        let localId = await this.adapter.mappingDb.getLocalId(globalId);

        // Save or update based on entity type
        if (mapping.tableName === "users") {
            // Create or update user...
        } else if (mapping.tableName === "groups") {
            // Create or update group...
        }
        
        res.status(200).send();
    } catch (e) {
        console.error("Webhook error:", e);
        res.status(500).send();
    }
};

## References

- [Awareness Protocol](/docs/W3DS%20Protocol/Awareness-Protocol) — Webhook payload and delivery
- [eVault](/docs/Infrastructure/eVault) — Webhook delivery from eVault
- [Ontology](/docs/Infrastructure/Ontology) — Schema IDs and schema registry
- [Web3 Adapter](/docs/Infrastructure/Web3-Adapter) — `fromGlobal` and mapping